home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3dm / audio / alReadBuffers.z / alReadBuffers
Encoding:
Text File  |  1998-10-20  |  8.9 KB  |  199 lines

  1.  
  2.  
  3.  
  4. aaaallllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))                                          aaaallllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      alReadBuffers - read flexibly interleaved or non-interleaved audio data
  10.      from an audio port
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiioooo....hhhh>>>>
  14.  
  15.      iiiinnnntttt aaaallllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrrssss((((ccccoooonnnnsssstttt AAAALLLLppppoooorrrrtttt ppppoooorrrrtttt,,,, vvvvooooiiiidddd ********bbbbuuuuffffssss,,,, iiiinnnntttt ****ssssttttrrrriiiiddddeeeessss,,,, ccccoooonnnnsssstttt iiiinnnntttt ffffrrrraaaammmmeeeeccccoooouuuunnnntttt))))
  16.  
  17. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR
  18.      _p_o_r_t         is the audio input port from which you want to read samples.
  19.                   This is the returned value of an aaaallllOOOOppppeeeennnnPPPPoooorrrrtttt((((3333ddddmmmm)))) call.
  20.  
  21.      _b_u_f_s         is an array of pointers to sample buffers, each element of
  22.                   which corresponds to a single channel of audio input.
  23.  
  24.      _s_t_r_i_d_e_s      is an array of integers, one corresponding to each input
  25.                   channel. Each element indicates the number of interleaved
  26.                   channels you desire in the sample buffer for that channel.
  27.  
  28.      _f_r_a_m_e_c_o_u_n_t   is the number of sample frames that you want to read from
  29.                   the audio port.
  30.  
  31. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  32.      aaaallllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrrssss transfers data from an audio port to a set of buffers, or
  33.      to different locations in a single buffer. aaaallllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrrssss allows the
  34.      application to specify how the data is to be interleaved.
  35.  
  36.      _b_u_f_s is an array of pointers to sample buffers. Each element of _b_u_f_s
  37.      corresponds to one input channel. If the element is 0, that channel will
  38.      be ignored; this allows an application to only read audio from the
  39.      channels of interest.
  40.  
  41.      The sample buffers can be arbitrarily interleaved; the _s_t_r_i_d_e_s parameter
  42.      indicates the number of channels in each target sample buffer. For
  43.      example, if _s_t_r_i_d_e_s[_n] is 1, then bufs[n] will be mono; if _s_t_r_i_d_e_s[_n] is
  44.      2, then bufs[n] will be interleaved stereo, and aaaallllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrrssss will write
  45.      to every other sample in that buffer.  The elements of _s_t_r_i_d_e_s can have
  46.      any value. If _s_t_r_i_d_e_s is 0, all the sample buffers will be mono, and
  47.      aaaallllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrrssss does non-interleaved input.
  48.  
  49.      There must be exactly as many elements in _b_u_f_s and _s_t_r_i_d_e_s as the number
  50.      of channels specified for the port with aaaallllSSSSeeeettttCCCChhhhaaaannnnnnnneeeellllssss((((3333ddddmmmm)))).
  51.  
  52.      aaaallllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrrssss blocks until _f_r_a_m_e_c_o_u_n_t sample frames have been read from
  53.      the port.  If you do not wish to block, make sure that _f_r_a_m_e_c_o_u_n_t is less
  54.      than the return value of aaaallllGGGGeeeettttFFFFiiiilllllllleeeedddd((((3333ddddmmmm)))).
  55.  
  56.      The target format of each sample depends upon the configuration of the
  57.      audio port. Each sample can be an 8-, 16-, or 32-bit integer, or a
  58.      single- or double-precision floating-point value or subcode data; see
  59.      aaaallllSSSSeeeettttSSSSaaaammmmppppFFFFmmmmtttt((((3333ddddmmmm)))) and aaaallllSSSSeeeettttWWWWiiiiddddtttthhhh((((3333ddddmmmm)))) for a description of how these
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaallllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))                                          aaaallllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      formats work. By default, the sample format is 16-bit integer (short).
  75.  
  76.      Note that since an audio port contains an internal queue, samples read
  77.      from the port may have come in some time ago. For precise synchronization
  78.      of audio and other media, use aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeTTTTiiiimmmmeeee((((3333ddddmmmm)))) and
  79.      aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeNNNNuuuummmmbbbbeeeerrrr((((3333ddddmmmm)))) to determine when samples arrived.
  80.  
  81.      In order to achieve the best possible performance, aaaallllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrrssss does not
  82.      attempt to verify that _p_o_r_t, _b_u_f_s, or _s_t_r_i_d_e_s are valid. You should make
  83.      certain these values are valid before passing them as arguments to
  84.      aaaallllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrrssss.
  85.  
  86. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  87.      The following code fragment opens an 8-channel audio input port and reads
  88.      8 separate mono buffers from it. For more examples, see the man page for
  89.      aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm)))) and the code in /usr/share/src/dmedia/audio.
  90.  
  91.           ALport p;
  92.           short buf[8][1000];
  93.           void *bufs[8];
  94.           int i,j;
  95.           ALconfig c;
  96.  
  97.           c = alNewConfig();
  98.           if (!c) {
  99.               printf("config create failed:%s\n", alGetErrorString(oserror()));
  100.               exit(-1);
  101.           }
  102.  
  103.           alSetChannels(c, 8);
  104.  
  105.           /* open a port with our configuration */
  106.           p = alOpenPort("alReadBuffers example","r",c);
  107.  
  108.           if (!p) {
  109.               printf("port open failed:%s\n", alGetErrorString(oserror()));
  110.               exit(-1);
  111.           }
  112.  
  113.           /*
  114.            * set up bufs
  115.            */
  116.           for (i = 0; i < 8; i++) {
  117.                   bufs[i] = buf[i];
  118.           }
  119.  
  120.           alReadBuffers(p, bufs, 0, 1000);          /* read 1000 8-channel frames */
  121.           }
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. aaaallllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))                                          aaaallllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  141.      aaaallllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrrssss always returns 0.
  142.  
  143. NNNNOOOOTTTTEEEE
  144.      This function was introduced via patch to IRIX 6.3 and 6.4, and is
  145.      present by default in later OS releases.  You should ensure that the
  146.      target system will have the functionality before calling this function;
  147.      otherwise, your program will crash when you attempt to make the function
  148.      call. To determine if the feature is present, check the value of
  149.      AL_VERSION on the system resource. The parameter must be present and its
  150.      value must be at least 6.
  151.  
  152.                   pv.param = AL_VERSION;
  153.                   alGetParams(AL_SYSTEM,&pv,1);
  154.                   if (pv.sizeOut < 0 || pv.value.i < 6) {
  155.                       /* feature not present */
  156.                   }
  157.  
  158.  
  159.  
  160. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  161.      alOpenPort(3dm), alGetFillable(3dm), alGetFilled(3dm),
  162.      alSetChannels(3dm), alSetWidth(3dm), alReadFrames(3dm),
  163.      alZeroFrames(3dm), alSetConfig(3dm), alSetQueueSize(3dm),
  164.      alSetSampFmt(3dm), alSetFloatMax(3dm)
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.